qacli view

This subcommand allows you to output a summary of the diagnostics from a previous analysis.

Usage

view  [-P <directory>] [-K <config name>] [-C <solution-name>] [-R] [-t <SUMMARY>] -m <HTML|STDERR|STDOUT|XML> [--output-name <filename prefix>] [-o <directory>] [-F <filelist>] [-X <max-count-filter>] [-S <0|1|2|3|4|5|6|7|8|9>] [-v <0|1|2|3|4|5|6|7|8|9>] [-N <msg-filter>] [-O <msg-filter>] [-D <NONE|SINGLE|DUPLICATE|CMA>] [-T <ALL|BASELINE|COMMENT|DASHBOARD|INTERACTIVE|MACRO|PRAGMA|VALIDATE>] ...  [-Y] [-Z] [-n] [-i <indent>] [--] [-h] <source-file>

Extended Description

The view subcommand allows you to output the analysis results in a variety of mediums (Text, XML, HTML). Filtering allows the user to finely control what details, from which files make it into the output.

The type of output is set using the --type (-t) option. It can currently only have the following value:

  • SUMMARY - Outputs a severity summary of all diagnostics for the project into a single file. See Severity Summary (SUMMARY) for more information.

The output can be in one of several different formats (or mediums):

  • HTML - For each source file, output results to an HTML file.
  • STDERR - Output results as text, to standard error.
  • STDOUT - Output results as text, to standard output.
  • XML - For each source file, output results to an XML file.

It is possible to view results on the command line or output them to a file.

The original source remains Read Only and, as such, it will never be modified or have its modification time changed under any circumstances, regardless of the commands invoked.
Switch shortcuts can be chained. For example: qacli view -P <directory> -m STDOUT -rs

Options

Name, shorthand Default Description
--config, -K   For projects with multiple configurations, specify which configuration to use. If none specified, then the default will be used.
--cma-solution, -C   Specify the name of the cross-module analysis (CMA) solution to view. Using this option implies that viewing will be conducted on all Perforce QAC projects involved in the solution. Use --qaf-project to specify the project to use for viewing the results of the analysis (the first Perforce QAC project of the CMA solution is used by default).
--exclude-zero-dependent-rust, -Y   By default, all Rust modules are output, including those with a non zero amount of diagnostics. This option hides dependent Rust modules with zero diagnostics from the output.
--files, -F   Specify a path to a file containing a list of files for which to view results. If not supplied, results for all files in the project will be presented.
--help, -h   Displays usage information and exits.
--ignore-rest, --   Ignores the rest of the labelled arguments following this flag.
--include-zero-headers, -Z   By default, all source files are output, but only headers with a non-zero number of diagnostics are shown. This option will show all source and header files, regardless of the diagnostics count.
--indent, -i -1 or 0 Sets the number of spaces or tabs that will be output for each level of indentation (XML only). Positive numbers indicate spaces, negative numbers tabs. The default for XML is -1.
--max-count, -X   Introduces a limit on the number of times that any message is displayed. The default of 0 indicates no limit is applied.
--max-severity, -v   Filter messages whose severity is more than the supplied severity. This can be used with the --min-severity option to only output messages within a severity range or specific severity. 9 is acceptable, but will filter nothing.
--min-severity, -S   Filter messages whose severity is less than the supplied severity. This can be used with the --max-severity option to only output messages within a severity range or specific severity. 0 is acceptable, but will filter nothing.
--medium, -m   Specify the medium through which to show results.
--multi-homed-format, -D  

Format to use when displaying multi-homed (homeless) diagnostics, such as diagnostics from CMA. Possible values are:

  • NONE - Do not output any multi-homed diagnostics (Default)
  • DUPLICATE - Duplicate each diagnostic to each location.
  • SINGLE - Output each diagnostic to a single location. SUMMARY & DIAGLST (excluding embedded headers).
  • CMA - Output to a CMA 'file'. SUMMARY only.
--nomsg, -N   Suppresses the display of the specified messages. Message numbers can be specified individually, or as a list, range or a combination of both: --nomsg 2356 --nomsg 1234,1236,1240 --nomsg 2111,2200-2300
--no-header-messages, -n   Do not show diagnostics from header files.
--only, -O   Only the specified warning messages will be shown. Message numbers can be specified individually, or as a list, range or a combination of both: --only 2356 --only 1234,1236,1240 --only 2111,2200-2300
--output-name   For commands that produce a single file, such as -t SUMMARY -m XML, prefix the filename with this value. This enables customization of the filename.
--output-path, -o   Specify a path to an existing directory, with write access, to place the output files in. This option is only valid when the medium option is set to HTML or XML. Duplicate files will not be overwritten, and their name will have a unique number appended.
--qaf-project, -P   Specify a path to a valid Perforce QAC project for which to view results.
--relative-paths, -R   Source files will be shown relative to the Source Root folder.
--suppression-filter, -r   Specify which suppressed diagnostics to allow through the filter. Possible options are: ALL, BASELINE, COMMENT, DASHBOARD, INTERACTIVE, MACRO, PRAGMA, and VALIDATE. The format specifier 'Suppression Justification' (%j) will only be populated if you have selected this option. DASHBOARD and VALIDATE are synonyms for INTERACTIVE.
--type, -t SUMMARY

Specify the format that the results are presented in:

  • SUMMARY - Summary table detailing diagnostics in each severity level

Examples

To output the results for a Perforce QAC project to standard output, issue the following command:

qacli view -P <directory> --type SUMMARY --medium STDOUT

To output to standard error, replace STDOUT with STDERR in the above command.

When the argument to the --medium option is set to HTML or XML, a directory can be specified. Files will be output to this directory:

qacli view -P <directory> -m HTML --output-path <directory>

The directory must exist.

Severity Summary (SUMMARY)

To output a concise severity summary of a project use --type SUMMARY. For example:

qacli view -P <directory> -m STDOUT --type SUMMARY

This will output the summary to the console, where it can be redirected to a file if needed.

Naturally, you can also output to a HTML or XML file. By default, the file will be called severity_summary.xml (or .html) and be in the current working directory.

To output to another directory, use --output-path. For example:

qacli view -P <directory> -m XML --type SUMMARY --output-path ../frodo

To output to a specific named file, use --output-name. For example:

qacli view -P <directory> -m XML --type SUMMARY --output-name My_Sev_Summary

The appropriate extension (.xml or .html) will automatically be added. Both --output-path and --output-name can be used together to exactly dictate the location and name for the output file.

For XML output an additional schema that describes the file format will be output. It will be called cli_view_severity_summary.xsd

For multi-project CMA solutions one file per underlying project will be created. The name will be severity_summary.xml (or .html), then severity_summary(1).xml and so on.